home *** CD-ROM | disk | FTP | other *** search
/ Risc World 5 / Risc World 5.iso / SOFTWARE / Issue5 / PD / DIRSYNC / Extras / DeepKeys < prev    next >
Text File  |  2001-03-26  |  5KB  |  103 lines
  1.  
  2.  DeepKeys 2.04 (26-Mar-2001) © Cerilica 2001
  3.  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  4.  
  5.  DeepKeys has two functions, it implements a word-deep rather than byte-deep
  6.  keyboard buffer, and it extends the Wimp KeyPress message with modifiers and
  7.  physical key number.
  8.  
  9.  DeepKeys can be distributed with any program, PD or commercial, providing that
  10.  this documentation is included intact, and that the following credit is
  11.  reproduced in any other documentation, manuals and/or help files:
  12.  
  13.     DeepKeys © Cerilica Ltd 2001  Contact: <simon@cerilica.com>
  14.  
  15.  
  16.  Keyboard Buffer
  17.  ~~~~~~~~~~~~~~~
  18.  DeepKeys implements a word-sized keyboard buffer. Consequently all system
  19.  calls that deal with the keyboard buffer now input and output word-sized
  20.  values. "Deep" key ranges are allocated by Alan Glover at Pineapple Software
  21.  <allocate@pinesoft.demon.co.uk>.
  22.  
  23.  InsV, RemV and CnpV handle word-sized keypress codes, but block mode is still
  24.  byte-orientated. OS_Byte 138,0,<code> can take "deep" key codes, and OS_ReadC
  25.  returns word-sized values.
  26.  
  27.  
  28.  KeyPress Poll Event
  29.  ~~~~~~~~~~~~~~~~~~~
  30.  DeepKeys installs a wimp filter which extends the normal keypress event. Poll
  31.  reason 8 returns a word-sized keypress code at block+24 as normal, but this
  32.  followed by a new information word at block+28 containing the state of the
  33.  modifier keys at the time the keypress was detected, and the physical key
  34.  number of the non-modifier key generating the keypress:
  35.  
  36.   +24 KeyPress code (word)
  37.   +28 DeepKey information:
  38.       b0 Left Shift    b1 Right Shift
  39.       b2 Left Ctrl     b3 Right Ctrl
  40.       b4 Left Alt      b5 Right Alt
  41.       b6 Left Logo     b7 Right Logo
  42.       b8 Menu key
  43.       b9-14 reserved (0)
  44.       b15 Always 0
  45.       b16-31 Physical key number
  46.  
  47.  If an application requires DeepKeys, it should RMEnsure it. DeepKeys has been
  48.  allocated the common installation point of "<Boot$ToBeLoaded>.!!DeepKeys"
  49.  (note double pling), or it can be included within the application.
  50.  
  51.  If an application wants to make use of DeepKeys if available, but does not
  52.  require it, DeepKey's presence can be detected by setting bit 15 of block+28
  53.  before calling Wimp_Poll or Wimp_PollIdle - this bit is guaranteed to be clear
  54.  in a Key Pressed Event if the DeepKeys information word is present.
  55.  
  56.  Most keyboards generate key codes for the Logo and Menu keys (Cerilica's MMK
  57.  certainly does), but DeepKeys also treats them as modifiers, so an individual
  58.  application can use combinations such as Logo-A just as if it were Ctrl-A.
  59.  When operating like this, the code generated by the initial Logo or Menu
  60.  keypress must be ignored (but not passed on).
  61.  
  62.  The physical key number can be used to assign different actions to sets of
  63.  keys that generate the same keypress code - Return and Enter for example.
  64.  When implementing such a scheme, make sure that the DEFAULT action is that
  65.  assigned to the more-common keypress, eg:
  66.  
  67.    CASE block!24 OF
  68.      WHEN 13:REM Return, Enter or Ctrl-M
  69.        CASE (block!28)>>>16 OF
  70.          WHEN &67: PROCkeypress_ENTER
  71.          WHEN &54: PROCkeypress_CTRL_M
  72.          OTHERWISE:PROCkeypress_RETURN
  73.        ENCASE
  74.  
  75.  This ensures sensible operation with future keyboards, and with keypresses
  76.  not generated by the keyboard - see following section. Please note that to
  77.  allow the Logo and Menu keys to act as modifiers, they do not return a valid
  78.  physical key number when pressed in isolation.
  79.  
  80.  Problems
  81.  ~~~~~~~~
  82.  RemV block mode cannot sensibly be used - word values in the buffer will be
  83.  truncated to their lowest eight bits.
  84.  
  85.  Key codes inserted into the buffer by software, rather than by the keyboard,
  86.  do not have modifier or physical keys associated with them. When delivered
  87.  to a Wimp program it will report the state of the keyboard modifiers at the
  88.  time of the simulated keypress, and the physical key number of the last real
  89.  keypress. This physical key number will NOT match the key code inserted. This
  90.  is why Wimp applications must be careful about interpreting the physical key
  91.  number, as described above.
  92.  
  93.  The DeepKeys module does not pass keyboard buffer events on to existing
  94.  claimants of the InsV, RemV and CnpV vectors, and so must be loaded first to
  95.  avoid disabling some utilities - hence the allocated install position
  96.  "<Boot$ToBeLoaded>.!!DeepKeys". This is a consequence of the way these vectors
  97.  are used, and cannot be avoided without vector claimant prioritisation, as
  98.  performed by Cerilica's VectorExtend module.
  99.  
  100.  
  101.  DeepKeys is copyright Cerilica Limited and was written by Simon Birtwistle.
  102.  <http://www.cerilica.com/>                      <mailto:simon@cerilica.com>
  103.